Place API
Best practices
This API meets the following industry and business rules to ensure compliance with best practices as defined by the Ultra-Fast Broadband (UFB) BSS/OSS Business Interaction Framework (BIF).
| TCF industry rules | Description |
|---|---|
| TCF-IR002 | The minimum information required to return a partial list of location result(s) when performing an address-based request is a street name. |
| Chorus-IR005 | The following rules apply: - If any search result list is less than or equal to 200 we will return all results. - Where a search finds more than 200 results, the response will return 200 results (in no specific order) and indicate the total amount of results up to a maximum of 1000. - Refine the search criteria to narrow your results. |
| Chorus business rules | Description |
|---|---|
| Chorus-BIC008-1 | If the order has reached the state "Acknowledged" and the substate "Received" but has not been "Completed" or "Cancelled" then the order will be included in the response irrespective of who owns the order. |
| Chorus-BIC008-2 | If the order is a "Move" order, this query will not return the "Move From" value. Example: If an existing product is at location A and there is an open order (Move Primary; from location A to location B), the query will return the following for: - Location A, product and ONT details but not relinquishing order - Location B, product, ONT details and order details. |
| Chorus-BIC008-3 | If the order is a "Transfer" order, this query will not return the "losing RSP" details. Example: If an existing product is at location A and there is an open order (Transfer Primary; from product 1 to product 2), the query will return the following: - Location A, product 1, ONT details and any order details. |
| Chorus-PlaceAPI-4 | SAM ID, TUI ID, ONT Serial Number and Product ID are ID-based query parameters. They are mutually exclusive so only one of them can be used in a query. Note: Using any parameter alongside an ID-based query will cause the search to return error. Example: GET /places?samId=123&ontSerialNumber=ALCLF1234567 Result: If there are too many conflicting query parameters, the Place API will reject the request and return error code: FCL-400-22 |
| Chorus-PlaceAPI-5 | locationDescriptor, unit, level, fullStreetNumber, streetNr, streetNrSuffix, streetNrLast, streetName, streetType, streetSuffix, suburb, town and postcode are address-based query parameters. More than one of these parameters can be provided; but a place must match the criteria of each of the parameters provided, in order to be included in the response. Notes: - The more specific your search, the more accurate the results will be. - The address-based query based parameters are mutually exclusive with ID based query parameters so they cannot be used at the same time (refer to Chorus-PlaceAPI-4). Example: GET /places?tuiId=1234567890&streetName=willis Result: Place API will reject the request if address-based query parameter and ID-based parameter used and return error code: FCL-400-22. |
| Chorus-PlaceAPI-6 | Searching for the address or location number is possible with either: - fullStreetNumber OR - streetNr OR streetNrSuffix OR streetNrLast OR unit. Note: You can use either fullStreetNumber or any of the detailed address parameters above but not both simultaneously. Error example: GET/places?fullStreetNumber=1&streetNr=1&streetName=Willis Result: Place API will reject the request if conflicting parameters are detected in the request and return error code: FCL-400-13. |
| Chorus-PlaceAPI-7 | If any of the detailed street number parameters are provided (streetNr, streetNrSuffix, streetNrLast, unit) then exact match will be used to find matching addresses. Example: GET/places?fullStreetNumber=1&streetName=Willis">/places?streetNr=1&streetName=Willis&streetType=Street Result: Place API will return all addresses matching exactly with 1 Willis Street. |
| Chorus-PlaceAPI-8 | fullStreetNumber may be used to execute a partial match over all addresses matching the given criteria. Note: This will perform a partial match on the details provided. If the details match the query parameters, then multiple results may be returned. Example: GET/places?fullStreetNumber=1&streetName=Willis Result: If this is an apartment block, all units on 1 Willis Street Wellington will be returned. |